Configuration Files

By far the easiest approach to defining your ModeShape configuration is to use a configuration file. As mentioned above, you'll want to do this if your application uses the standard and implementation-independent RepositoryFactory mechanism to obtain the JCR Repository reference.

Here is an example configuration file used in the repository example covered in the Getting Started document, though it has been slightly simplified for clarity):

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns:mode="http://www.modeshape.org/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0">
  <!--
  Define the JCR repositories
  -->
  <mode:repositories>
      <!--
      Define a JCR repository that accesses the 'Cars' source directly.
      This of course is optional, since we could access the same content through 'vehicles'.
      -->
      <mode:repository jcr:name="car repository" mode:source="Cars">
          <mode:options jcr:primaryType="mode:options">
              <mode:option jcr:name="jaasLoginConfigName" mode:value="modeshape-jcr"/>
          </mode:options>
          <mode:descriptors>
            <!--
            	This adds a JCR Repository descriptor named "myDescriptor" with a value of "foo".
            	So this code:
            	Repository repo = ...;
            	System.out.println(repo.getDescriptor("myDescriptor");

            	Will now print out "foo".
            -->
            <myDescriptor mode:value="foo" />
          </mode:descriptors>
          <!--
                Import the custom node types defined in the named files. The values
                can be an absolute path to a classpath resource, an absolute file system
                path, a relative path on the file system (relative to where the process was
                started from), or a resolvable URL. If more than one node type definition
                file is needed, the files can be listed as a single comma-delimited string
                in the 'mode:resource' attribute of the 'jcr:nodeTypes' element, or listed
                individually using multiple mode:resource child elements (as shown below).
            -->
          <jcr:nodeTypes>
	           <mode:resource>/org/example/my-node-types.cnd</mode:resource>
	           <mode:resource>/org/example/additional-node-types.cnd</mode:resource>
	        </jcr:nodeTypes>
      </mode:repository>
  </mode:repositories>
   <!--
   Define the sources for the content. These sources are directly accessible using the
   ModeShape-specific Graph API.
   -->
   <mode:sources jcr:primaryType="nt:unstructured">
       <mode:source jcr:name="Cars"
              mode:classname="org.modeshape.graph.connector.inmemory.InMemoryRepositorySource"
              mode:retryLimit="3" mode:defaultWorkspaceName="workspace1">
	           <mode:predefinedWorkspaceNames>workspace2</mode:predefinedWorkspaceNames>
	           <mode:predefinedWorkspaceNames>workspace3</mode:predefinedWorkspaceNames>
       </mode:source>
   </mode:sources>
   <!--
   Define the sequencers. This is an optional section. For this example, we're not using any sequencers.
   -->
   <mode:sequencers>
       <!--mode:sequencer jcr:name="Image Sequencer">
           <mode:classname>
           	org.modeshape.sequencer.image.ImageMetadataSequencer
           </mode:classname>
           <mode:description>Image metadata sequencer</mode:description>
           <mode:pathExpression>/foo/source => /foo/target</mode:pathExpression>
           <mode:pathExpression>/bar/source => /bar/target</mode:pathExpression>
       </mode:sequencer-->
   </mode:sequencers>
   <mode:mimeTypeDetectors>
       <mode:mimeTypeDetector jcr:name="Detector"
                             mode:description="Standard extension-based MIME type detector"/>
   </mode:mimeTypeDetectors>
</configuration>

Programmatic Configuration

Most likely you'll define your configuration in a file. But there are some situations where it's far easier - even necessary - to programmatically configure ModeShape. For example, you may not be able to predefine a configuration, because it needs parameters and information known only at runtime.

One obvious approach is to write code that takes this new information and generates a ModeShape configuration file. The challenge here is that a sizable amount of code may be required just to write out the XML file in the correct format.

Perhaps an easier approach is to use the ModeShape JcrConfiguration class to programmatically construct the configuration, and then have it write the configuration out to a file. You can even load a starting configuration, programmatically modify it, and write it out to a file. From there, your application can use the standard and implementation-independent JCR API to find and use the Repository instances.

The JcrConfiguration class is used by ModeShape to read in the configuration files, but it was also designed to have an easy-to-use API that makes it easy to configure each of the different kinds of components, especially when using an IDE with code completion. The next few sections describe how to configure the various parts of a ModeShape configuration.

JcrConfiguration config = ...
config.repositorySource("source A")
     .usingClass(InMemoryRepositorySource.class)
     .setDescription("The repository for our content")
     .setProperty("defaultWorkspaceName", workspaceName);

JcrConfiguration config = ...
config.repository("repository A")
     .addNodeTypes("myCustomNodeTypes.cnd")		// can be called multiple times
     .setSource("source 1")
     .registerNamespace("acme","http://www.example.com/acme")
     .setOption(JcrRepository.Option.JAAS_LOGIN_CONFIG_NAME, "modeshape-jcr");

JcrConfiguration config = ...
config.sequencer("Image Sequencer")
     .usingClass("org.modeshape.sequencer.image.ImageMetadataSequencer")
     .loadedFromClasspath()
     .setDescription("Sequences image files to extract the characteristics of the image")
     .sequencingFrom("//(*.(jpg|jpeg|gif|bmp|pcx|png|iff|ras|pbm|pgm|ppm|psd)[*])/jcr:content[@jcr:data]")
     .andOutputtingTo("/images/$1");

JcrConfiguration config = ...
config.mimeTypeDetector("Extension Detector")
     .usingClass(org.modeshape.graph.mimetype.ExtensionBasedMimeTypeDetector.class);

JcrConfiguration config = ...
String pathToFile = ...

// Save any changes before this point in the configuration repository ...
configuration.save();
// And now write out the configuration repository to a file ...
configuration.storeTo(pathToFile);

Loading from a Configuration Repository

So far, we've seen how to load a configuration from a file, how to programmatically define a configuration and write it out to a file. In this section, we'll see how ModeShape can load its configuration from another repository.

The first step is to create and configure the RepositorySource instance that we'll use to access the repository where the configuration is stored. Then, create a JcrConfiguration instance and load from this source:

RepositorySource configSource = ...
JcrConfiguration config = new JcrConfiguration();
configuration.loadFrom(configSource);

The loadFrom(...) method can be called any number of times, but each time it is called it completely wipes out any current notion of the configuration and replaces it with the configuration found in the file.

There is an optional second parameter that defines the name of the workspace in the supplied source where the configuration content can be found. It is not needed if the workspace is the source's default workspace. There is an optional third parameter that defines the Path within the configuration repository identifying the parent node of the various configuration nodes. If not specified, it assumes "/". This makes it possible for the configuration content to be located at a different location in the hierarchical structure. (This is not often required, but it is very useful if you ModeShape configuration file is embedded within another XML file.)

Once the JcrConfiguration has been loaded from a RepositorySource, the JcrConfiguration instance can be used to modify the configuration and then save those changes back to the repository. This technique can be used to place a configuration into a repository (such as a database) for the first time:

RepositorySource configSource = ...	// a RepositorySource to an empty source
JcrConfiguration config = new JcrConfiguration();

// Bind the configuration to the repository source (which is initially empty)...
configuration.loadFrom(configSource);

// Now load a configuration from a file (or construct one programmatically) ...
String pathToFile = ...
configuration.loadFrom(pathToFile);

// Now save the configuration into the source ...
configuration.save();

Now you can load this configuration in multiple processes, using the approach mentioned above.

Built-in Providers

ModeShape comes with several AuthorizationProvider implementations that are automatically configured with every Repository, depending upon other settings and options. These providers are as follows:

• JaasProvider uses JAAS for all authentication and role-based authorization. This provider authenticates clients that login to the Repository with a SimpleCredentials object, where the username and password match that in the JAAS policy, or a JaasCredentials constructed with a specific and already-authenticated JAAS LoginContext. This provider can be disabled by setting the jaasLoginConfigName configuration option to an empty (i.e., zero-length) value; otherwise, the option defines the name of the JAAS login configuration and will default to "modeshape-jcr" if not explicitly set. (This provider also works in some J2EE containers, in which the JAAS Subject is not available via the standard JAAS API and instead requires use of the JACC API, which many J2EE containers support).

• SeamSecurityProvider delegates all authentication and role-based authorization to the Seam Security framework. This provider authenticates clients that login to the Repository with no need to pass a Credentials object. Note this does require obtaining a session for each servlet request, which is actually how the JCR API was intended to be used within web applications. This provider is automatically enabled when the Seam Security Identity class is found on the classpath.

• ServletProvider delegates all authentication and role-based authorization to the servlet framework. This provider authenticates clients that login to the Repository with a ServletCredentials object, which can be constructed with the HttpServletRequest. Note this does require obtaining a session for each servlet request, which is actually how the JCR API was intended to be used within web applications. This provider is automatically enabled when the HttpServletSession class is found on the classpath.

• AnonymousProvider will allow clients without Credentials to operate upon the repository, and will use role-based authorization based upon the roles defined by the anonymousUserRoles configuration option. This provider authenticates clients that provide an AnonymousCredentials to the Repository's login(...) methods or use one of the login(...) methods that does not take a Credentials object.

  The SecurityContextProvider is also configured only when the useSecurityContextCredentials configuration option is set to 'true'. This provider authenticates clients that pass a SecurityContextCredentials object, and delegates all authentication to the embedded SecurityContext. This deprecated approach is not enabled by default, and will be removed in the next major release of ModeShape. It remains in place to enable applications that use this older and less attractive approach to upgrade to ModeShape 2.6 (or later) without breaking their authentication mechanism.

Custom Providers

It is possible to provide your own authentication and authorization logic by providing one (or more) classes that implements the AuthorizationProvider interface, specifying the names of these classes in the configuration (see below), and making the classes available on the correct classpath.

Implementing the AuthorizationProvider interface is pretty straightforward. Your class needs a no-arg constructor, and the authenticate method must simply authenticate the credentials for the named repository and workspace. If the credentials are not authenticated, simply return null. Otherwise, simply create an ExecutionContext instance (from the ExecutionContext supplied in the repositoryContext parameter) to contain an appropriate SecurityContext instance for the authenticated user. As mentioned above, the SecurityContext should also implement the AuthorizationProvider interface for non-role-based authorization.

For example, let's imagine that our JCR application has its own authentication and authorization system. We can integrate with that by create a new Credentials implementation called MyAppCredentials to encapsulate any information needed by the authentication/authorization system, which we'll assume is accessed by a singleton class SecurityService. We can then implement AuthenticationProvider as follows:

public class MyAppAuthorizationProvider implements AuthorizationProvider {

  private String appName;

  /**
   * Any public JavaBean properties can be set in the configuration
   */
  public void setApplicationName( String appName ) {
    this.appName = appName;
  }

  /**
   * Authenticate the user that is using the supplied credentials. If the supplied
   * credentials are authenticated, this method should construct an ExecutionContext
   * that reflects the authenticated environment, including the context's valid
   * SecurityContext that will be used for authorization throughout the Session.
   * <p>
   * Note that each provider is handed a map into which it can place name-value
   * pairs that will be used in the Session attributes of the Session that results
   * from this authentication attempt. ModeShape will ignore any attributes if
   * this provider does not authenticate the credentials.
   * </p>
   *
   * @param credentials the user's JCR credentials, which may be an
   *  AnonymousCredentials if authenticating as an anonymous user
   * @param repositoryName the name of the JCR repository; never null
   * @param workspaceName the name of the JCR workspace; never null
   * @param repositoryContext the execution context of the repository, which
   * may be wrapped by this method
   * @param sessionAttributes the map of name-value pairs that will be placed
   *  into the Session's attributes; never null
   * @return the execution context for the authenticated user, or null if
   * this provider could not authenticate the user
   */
  public ExecutionContext authenticate( Credentials credentials,
                                        String repositoryName,
                                        String workspaceName,
                                        ExecutionContext repositoryContext,
                                        Map<String,Object> sessionAttributes );
    if ( credentials instanceof MyAppCredentials ) {
      // Try to authenticate ...
      MyAppCredentials appCreds = (MyAppCredentials)credentials;
      String user = appCreds.getUser();
      Object token = appCreds.getToken();
      AppCreds creds = SecurityService.login(appName,user,token);
      if ( creds != null ) {
        // We're in ...
        SecurityContext securityContext = new MyAppSecurityContext(creds);
        return repositoryContext.with(securityContext);
      }
    }
    return null;
  }
}

where the MyAppSecurityContext is as follows:

public class MyAppSecurityContext
            implements SecurityContext, AuthorizationProvider {
  private final AppCreds creds;
  public MyAppSecurityContext( AppCreds creds ) {
    this.creds = creds;
  }

  /**
   * {@inheritDoc SecurityContext#getUserName()}
   *
   * @see SecurityContext#getUserName()
   */
  public final String getUserName() {
      return creds.getUser();
  }

  /**
   * {@inheritDoc SecurityContext#hasRole(String)}
   *
   * @see SecurityContext#hasRole(String)
   */
  public final boolean hasRole( String roleName ) {
      // shouldn't be called since we've implemented AuthorizationProvider
      return false;
  }

  /**
   * {@inheritDoc}
   *
   * @see org.modeshape.graph.SecurityContext#logout()
   */
  public void logout() {
      creds.logout();
  }

  /**
   * {@inheritDoc}
   *
   * @see org.modeshape.jcr.security.AuthorizationProvider.hasPermission
   */
  public boolean hasPermission( ExecutionContext context,
                           String repositoryName,
                           String repositorySourceName,
                           String workspaceName,
                           Path path,
                           String... actions ) {
    // This is imaginary and simplistic, but you'd implement any authorization logic here ...
    return this.creds.isAuthorized(repositoryName,workspaceName,path);
  }
}

Then we just need to configure the Repository to use this provider. In the ModeShape configuration files, there is an optional "mode:authenticationProviders" child element of "mode:repository", and within this fragment you can define zero or more authentication providers by specifying a name, the class, an optional description, and optionally any bean properties that should be called upon instantiation. (Note that the class will be instantiated only once per Repository instance). Here's an example configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns:mode="http://www.modeshape.org/1.0"
	             xmlns:jcr="http://www.jcp.org/jcr/1.0">
  <mode:repositories>
    <mode:repository jcr:name="MyApp Repository" mode:source="Store">
      ...
      <mode:authenticationProviders>
        <!-- Specify the providers in a manner similar to sequencer
             definitions are defined -->
        <mode:authenticationProvider jcr:name="CustomProviderA"
                    mode:classname="org.example.MyAppAuthorizationProvider">
          <mode:description>My authentication provider</mode:description>
          <!-- Set JavaBean properties on provider if needed -->
          <mode:appName>MyAppName</mode:appName>
        </mode:authenticationProvider>
        ...
      </mode:authenticationProviders>
      ...
    </mode:repository>
    ...
  </mode:repositories>
  ...
</configuration>

Enabling Clustering in ModeShape

A ModeShape configuration can have a "clustering" fragment that defines the name of the cluster and the JGroups configuration:

<mode:clustering clusterName="modeshape-cluster" configuration="jgroups-modeshape.xml" />

The "clusterName" is a string that is a logical name of the cluster; all engines connecting to the same name form a cluster. Any messages multicast from one engine in the cluster will be received by all other members of the cluster. Again, the cluster name is independent of the repositories managed by th

The "configuration" value is a string that is one of:

• the absolute file system path to the file containing the JGroups XML configuration;

• the relative file system path to the file containing the JGroups XML configuration, relative to the current working directory of the Java process;

• the name of a resource on the classpath containing the JGroups XML configuration;

• the URL that can be resolved to the JGroups XML configuration; or

• the string representation of JGroups configuration, either in XML format or the older string format.
  The format of this JGroups configuration will be described in the next section. If the "configuration" property is not given, ModeShape will use the default JGroups configuration (as defined by the specific JGroups version).

Here is an example of a "clustering" fragment defining a cluster named "modeshape-cluster" using the JGroups configuration defined in the "jgroups-modeshape.xml" file at the supplied URL:

<clustering clusterName="modeshape-cluster"
	  configuration="file://some/path/jgroups-modeshape.xml" />

This next example uses the JGroups configuration defined in the "jgroups-modeshape.xml" resource file on the classpath (or as an absolute path on a *nix system):

<clustering clusterName="modeshape-cluster"
	  configuration="/some/path/jgroups-modeshape.xml" />

Next is an example that specifies the JGroups configuration using the older string representation of the form:

<clustering clusterName="modeshape-cluster"
	  configuration="PROTOCOL(param=value;param=value):PROTOCOL:PROTOCOL" />

Of course, the "configuration" property can be specified as a child element, too (line breaks added for readability):

<clustering clusterName="modeshape-cluster">
	     <configuration>UDP(max_bundle_size="60000":max_bundle_timeout="30"):
		                  PING(timeout="2000"):...</configuration>
</clustering>

And finally an example that specifies the JGroups configuration using the newer XML representation (line breaks added for readability):

<clustering clusterName="modeshape-cluster">
	 <configuration><![CDATA[MODE27:Reference Guide]]>
	 </configuration>
</clustering>

Note that the this example uses a child XML element for the "configuration", along with a CDATA section, so that the XML configuration can be nested within the ModeShape configuration.

JGroups configuration

The JGroups configuration defines a protocol stack that is used for messaging, starting with the bottom-most protocol and ending with the top-most protocol.

An example of the newer-style JGroups XML format is:

<config>
   <UDP
        mcast_addr="${jgroups.udp.mcast_addr:228.10.10.10}"
        mcast_port="${jgroups.udp.mcast_port:45588}"
        discard_incompatible_packets="true"
        max_bundle_size="60000"
        max_bundle_timeout="30"
        ip_ttl="${jgroups.udp.ip_ttl:2}"
        enable_bundling="true"
        thread_pool.enabled="true"
        thread_pool.min_threads="1"
        thread_pool.max_threads="25"
        thread_pool.keep_alive_time="5000"
        thread_pool.queue_enabled="false"
        thread_pool.queue_max_size="100"
        thread_pool.rejection_policy="Run"
        oob_thread_pool.enabled="true"
        oob_thread_pool.min_threads="1"
        oob_thread_pool.max_threads="8"
        oob_thread_pool.keep_alive_time="5000"
        oob_thread_pool.queue_enabled="false"
        oob_thread_pool.queue_max_size="100"
        oob_thread_pool.rejection_policy="Run"/>
   <PING timeout="2000"
           num_initial_members="3"/>
   <MERGE2 max_interval="30000"
           min_interval="10000"/>
   <FD_SOCK/>
   <FD timeout="10000" max_tries="5" />
   <VERIFY_SUSPECT timeout="1500"  />
   <BARRIER />
   <pbcast.NAKACK
                  use_mcast_xmit="false" gc_lag="0"
                  retransmit_timeout="300,600,1200,2400,4800"
                  discard_delivered_msgs="true"/>
   <UNICAST timeout="300,600,1200,2400,3600"/>
   <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
                  max_bytes="400000"/>
   <VIEW_SYNC avg_send_interval="60000"   />
   <pbcast.GMS print_local_addr="true" join_timeout="3000"
               view_bundling="true"/>
   <FC max_credits="20000000"
                   min_threshold="0.10"/>
   <FRAG2 frag_size="60000"  />
   <pbcast.STATE_TRANSFER  />
</config>

The older-style JGroups string format is of the form:

PROTOCOL(param1=value1:param2=value2):PROTOCOL:PROTOCOL

This format is generally harder to read and generally discouraged. Nevertheless, here's an example of the older string format defining the same stack as the previous XML example (line breaks have been added for readability):

UDP(
        mcast_addr="${jgroups.udp.mcast_addr:228.10.10.10}":
        mcast_port="${jgroups.udp.mcast_port:45588}":
        discard_incompatible_packets="true":
        max_bundle_size="60000":
        max_bundle_timeout="30":
        ip_ttl="${jgroups.udp.ip_ttl:2}":
        enable_bundling="true":
        thread_pool.enabled="true":
        thread_pool.min_threads="1":
        thread_pool.max_threads="25":
        thread_pool.keep_alive_time="5000":
        thread_pool.queue_enabled="false":
        thread_pool.queue_max_size="100":
        thread_pool.rejection_policy="Run":
        oob_thread_pool.enabled="true":
        oob_thread_pool.min_threads="1":
        oob_thread_pool.max_threads="8":
        oob_thread_pool.keep_alive_time="5000":
        oob_thread_pool.queue_enabled="false":
        oob_thread_pool.queue_max_size="100":
        oob_thread_pool.rejection_policy="Run"):
   PING(timeout="2000":
        num_initial_members="3"):
   MERGE2(max_interval="30000":
          min_interval="10000"):
   FD_SOCK:
   FD(timeout="10000":max_tries="5"):
   VERIFY_SUSPECT(timeout="1500"):
   BARRIER:
   pbcast.NAKACK(use_mcast_xmit="false":gc_lag="0":
                 retransmit_timeout="300,600,1200,2400,4800":
                 discard_delivered_msgs="true"):
   UNICAST(timeout="300,600,1200,2400,3600"):
   pbcast.STABLE(stability_delay="1000":desired_avg_gossip="50000":
                 max_bytes="400000"):
   VIEW_SYNC(avg_send_interval="60000"):
   pbcast.GMS(print_local_addr="true":join_timeout="3000"
              view_bundling="true"):
   FC(max_credits="20000000":
      min_threshold="0.10"):
   FRAG2(frag_size="60000"):
   pbcast.STATE_TRANSFER

For more details on how to configure the JGroups stack, see the JGroups Manual.

Deploying ModeShape to JBoss AS 5 and 6

The JBoss Application Server (or JBoss AS) is a very popular open source Java application server, with an extremely healthy and active community. ModeShape offers a way to deploy ModeShape into JBoss AS versions 5.x or 6.x as as a central, shared service that can be monitored and administered using the embedded console.

ModeShape provides a downloadable ZIP file that can be unzipped into any JBoss AS profile. When you do this, that profile will contain all the files necessary for ModeShape to run when the server is started. The default configuration is for a single, in-memory repository with two users. However, other than basic playing, you will want to edit the configuration files to define a more robust, persistent and secure configuration.

There are two distribution ZIP files, one for JBoss AS 5.x and another for JBoss AS 6.x, and both file contains several components:

• JAR files for the JCR 2.0 API and ModeShape's small extensions to the JCR API on the global classpath (that is, in the "lib/" directory). These APIs are available to all deployed applications, services and components. The JCR API contains the "javax.jcr" packages and has no other dependencies. ModeShape's extensions define interfaces in the "org.modeshape.jcr.api" packages; these extend a few of the standard JCR API interfaces and add several methods to make them more useful.

• The ModeShape Service, represented as an exploded JAR file in the "deploy" directory. This is where the JcrEngine is running, though any application (or other JBoss service) can access its JCR Repository instances using the standard RepositoryFactory approach (covered in the next chapter) with JNDI URLs:

  jndi:jcr/local?repositoryName=repository

  By default, there is a single in-memory repository named "repository", but this can be changed by simply editing the "deploy/modeshape-services.jar/managedConfigRepository.xml" configuration file. All of ModeShape's standard sequencers and connectors (and JARs for their dependencies) are included, meaning they can be configured for use without worrying about adding JARs to the classpath. Feel free to remove any of the JARs are not needed for your custom configuration.

• A pair of JAAS properties files, located in the "conf/props/" directory, that come out of the box with an "admin" user (with password "admin") that has full read, write, and administration privileges, and a "guest" user (with password "guest") that has only read and write privileges. Simply edit these files to change users, passwords, and roles, or to configure JAAS differently.

• The ModeShape RESTful API, represented as an exploded WAR file in the "deploy" directory. This allows remote applications to interact with ModeShape to access and manipulate repository content using a RESTful API that uses JSON in the requests and responses. All ModeShape repositories can be accessed, and authentication is done using the ModeShape JAAS configuration.

• The ModeShape WebDAV API, represented as an exploded WAR file in the "deploy" directory. This web application allows external clients to access and manipulate the content in the ModeShape repositories using the standard WebDAV protocol. For example, you can mount a repository (or parts of it) as a network drive on most operating systems, and then upload or download files and folders using standard OS operations and graphical tools. All ModeShape repositories can be accessed, and authentication is done using the ModeShape JAAS configuration.

• A plugin for the embedded JBoss AS console, represented as a WAR file in the "deploy" directory. This plugin also works with RHQ administration, monitoring, alerting, operational control and configuration system. (We plan to add more metrics and operations over the next few releases, as we gain more experience using the ModeShape RHQ plugin.)

• A JDBC driver that allows applications also deployed on the same JBoss AS instance to query the repositories through JDBC. This driver is on the global classpath so it can be used in any deployed component. A single JDBC DataSource is also configured in the "deploy/modeshape-services.jar/modeshape-jdbc-ds.xml" file to use the single default in-memory repository available out of the box. Simply edit this file to add or change the DataSource definitions. The driver can also be used in a separate JVM to issue queries and access database metadata.

• A remote client JAR that can be used by Java applications to use JDBC or the RESTful API to remotely access a ModeShape repository deployed on JBoss AS. This JAR includes ModeShape's full JDBC driver.
  Here are the contents of this file:

conf/
conf/props/
conf/props/modeshape-roles.properties
conf/props/modeshape-users.properties
lib/
lib/jcr-2.0.jar
lib/modeshape-jcr-api-2.7.jar
lib/modeshape-jdbc-local-2.7.jar
deploy/
deploy/modeshape-jboss-beans.xml
deploy/modeshape-services.jar/
deploy/modeshape-services.jar/META-INF/
deploy/modeshape-services.jar/aperture-1.1.0.Beta1.jar
deploy/modeshape-services.jar/joda-time-1.6.jar
deploy/modeshape-services.jar/lucene-analyzers-3.0.2.jar
deploy/modeshape-services.jar/lucene-core-3.0.2.jar
deploy/modeshape-services.jar/lucene-regex-3.0.2.jar
deploy/modeshape-services.jar/lucene-snowball-3.0.2.jar
deploy/modeshape-services.jar/lucene-misc-3.0.2.jar
deploy/modeshape-services.jar/poi-3.6.jar
deploy/modeshape-services.jar/poi-scratchpad-3.6.jar
deploy/modeshape-services.jar/managedConfigRepository.xml
deploy/modeshape-services.jar/rdf2go.api-4.6.2.jar
deploy/modeshape-services.jar/META-INF/jboss-beans.xml
deploy/modeshape-services.jar/modeshape-cnd-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-common-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-connector-filesystem-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-connector-infinispan-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-connector-jbosscache-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-connector-jcr-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-connector-jdbc-metadata-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-connector-store-jpa-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-connector-svn-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-graph-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-jbossas-service-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-jcr-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-jdbc-ds.xml
deploy/modeshape-services.jar/modeshape-mimetype-detector-aperture-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-repository-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-search-lucene-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-sequencer-classfile-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-sequencer-cnd-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-sequencer-ddl-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-sequencer-java-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-sequencer-jbpm-jpdl-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-sequencer-msoffice-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-sequencer-teiid-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-sequencer-text-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-sequencer-xml-2.7.0.Final.jar
deploy/modeshape-services.jar/modeshape-sequencer-zip-2.7.0.Final.jar
deploy/modeshape-rest.war/
deploy/modeshape-rest.war/META-INF/
deploy/modeshape-rest.war/WEB-INF/
deploy/modeshape-rest.war/WEB-INF/lib/
deploy/modeshape-rest.war/META-INF/MANIFEST.MF
deploy/modeshape-rest.war/WEB-INF/jboss-web.xml
deploy/modeshape-rest.war/WEB-INF/lib/jaxrs-api-1.2.1.GA.jar
deploy/modeshape-rest.war/WEB-INF/lib/jettison-1.1.jar
deploy/modeshape-rest.war/WEB-INF/lib/modeshape-jcr-2.7.0.Final.jar
deploy/modeshape-rest.war/WEB-INF/lib/modeshape-web-jcr-2.7.0.Final.jar
deploy/modeshape-rest.war/WEB-INF/lib/modeshape-web-jcr-rest-2.7.0.Final.jar
deploy/modeshape-rest.war/WEB-INF/lib/resteasy-jaxb-provider-1.2.1.GA.jar
deploy/modeshape-rest.war/WEB-INF/lib/resteasy-jaxrs-1.2.1.GA.jar
deploy/modeshape-rest.war/WEB-INF/lib/resteasy-jettison-provider-1.2.1.GA.jar
deploy/modeshape-rest.war/WEB-INF/lib/scannotation-1.0.2.jar
deploy/modeshape-rest.war/WEB-INF/web.xml
deploy/modeshape-webdav.war/
deploy/modeshape-webdav.war/WEB-INF/
deploy/modeshape-webdav.war/WEB-INF/lib/
deploy/modeshape-webdav.war/WEB-INF/jboss-web.xml
deploy/modeshape-webdav.war/WEB-INF/lib/aperture-1.1.0.Beta1.jar
deploy/modeshape-webdav.war/WEB-INF/lib/modeshape-jcr-2.7.0.Final.jar
deploy/modeshape-webdav.war/WEB-INF/lib/modeshape-mimetype-detector-aperture-2.7.0.Final.jar
deploy/modeshape-webdav.war/WEB-INF/lib/modeshape-web-jcr-2.7.0.Final.jar
deploy/modeshape-webdav.war/WEB-INF/lib/modeshape-web-jcr-webdav-2.7.0.Final.jar
deploy/modeshape-webdav.war/WEB-INF/lib/webdav-servlet-2.0.1.jar
deploy/modeshape-webdav.war/WEB-INF/web.xml
deploy/admin-console.war/
deploy/admin-console.war/plugins/
deploy/admin-console.war/plugins/modeshape-jbossas-console-2.7.0.Final.jar

Your web application or JBoss service can use one of the JCR Repository instances running inside the ModeShape service by simply using the RepositoryFactory technique described earlier, with a URL such as:

jndi:jcr/local?repositoryName=repository

Be sure to use the correct repository name.

Since the JCR API JAR is on the global classpath, your web application can use the JCR API without having to include the JAR file in your application's WAR file. In fact, your application will likely get ClassCastExceptions if it does include the JCR API in its WAR file. Plus, if needed, your application can use ModeShape's "org.modeshape.jcr.api" extensions to the JCR API (again, on the global classpath), and should not need or use any of the classes or interfaces in the ModeShape implementation.

Embedding ModeShape in web apps for deployment to other servers

Each kind of web server or application server is different, but all servlet containers do provide a way of configuring objects and placing them into JNDI. ModeShape provides a JndiRepositoryFactory class that implements and that can be used in the server's configuration. The JndiRepositoryFactory requires two properties:

• configFile is required and specifies the path to the configuration file resource, which must be available on the classpath

• repositoryName is optional and specifies the name of a JCR repository that exists in the JCR configuration that should be registered in JNDI; if not provided, then the ModeShape engine will be registered in JDNI at the specified location.

Here's an example of a fragment of the conf/context.xml for Tomcat that registers the ModeShape engine in JNDI at "jcr/local":

<Resource name="jcr/local"
          auth="Container"
          type="org.modeshape.jcr.api.Repository"
          factory="org.modeshape.jcr.JndiRepositoryFactory"
          configFile="/resource/path/to/configuration.xml" />

The web application can then use the newer pattern specified by the JCR 2.0 specification to use the and RepositoryFactory:

String configUrl = "jndi:jcr/local?repositoryName=Cars";
Map<String, String> parameters = Collections.singletonMap("org.modeshape.jcr.URL", configUrl);
for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {
    repository = factory.getRepository(parameters);
    if (repository != null) break;
}

Alternatively, it's possible to use this JndiRepositoryFactory class to start up ModeShape and register an individual JCR Repository instance. Here's an example of a fragment of the conf/context.xml for Tomcat that registers the "Cars" repository in JNDI at "jcr/local/Cars":

<Resource name="jcr/local/Cars"
          auth="Container"
          type="javax.jcr.Repository"
          factory="org.modeshape.jcr.JndiRepositoryFactory"
          configFile="/resource/path/to/configuration.xml"
          repositoryName="Cars" />

The web application can then directly lookup the Repository instance in JNDI, as recommended in the older JCR 1.0 specification:

InitialContext initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
Repository repository = (Repository) envCtx.lookup("jcr/local/Cars");

or via the newer pattern using the JCR 2.0 RepositoryFactory-style lookup approach:

String configUrl = "jndi:jcr/local/Cars";
Map<String, String> parameters = Collections.singletonMap("org.modeshape.jcr.URL", configUrl);
for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {
    repository = factory.getRepository(parameters);
    if (repository != null) break;
}

Note that it is possible to have multiple Resource entries. The JndiRepositoryFactory ensures that only one JcrEngine is instantiated, but that a Repository instance is registered for each entry.

Before the server can start, however, all of the ModeShape jars need to be placed on the classpath for the server. JAAS also needs to be configured, and this can be done using the application server's configuration or in your web application if you're using a simple servlet container. For more details, see the Reference Guide.

Then, your web application needs to reference the Resource and state its requirements in its web.xml:

<resource-env-ref>
   <description>Repository</description>
   <resource-env-ref-name>jcr/local/Cars</resource-env-ref-name>
   <resource-env-ref-type>javax.jcr.Repository</resource-env-ref-type>
</resource-env-ref>

or

<resource-env-ref>
   <description>ModeShape Engine</description>
   <resource-env-ref-name>jcr/local</resource-env-ref-name>
   <resource-env-ref-type>org.modeshape.jcr.api.Repositories</resource-env-ref-type>
</resource-env-ref>

Note that the value of resource-env-ref-name fields must matche the value of the name attribute on the <Resource> tag in the context.xml described above. This is a must.

At this point, your web application can perform the lookup of the Repository object by using JNDI directly (or the more standard RepositoryFactory technique shown in the next chapter), create and use a Session, and then close the Session. Here's an example of a JSP page that does this:

<%@ page import="javax.naming.*, javax.jcr.*, org.jboss.security.config.IDTrustConfiguration" %>
<%!

static {
	// Initialize IDTrust
	IDTrustConfiguration idtrustConfig = new IDTrustConfiguration();
	try {
	    idtrustConfig.config("security/jaas.conf.xml");
	} catch (Exception ex) {
	    throw new IllegalStateException(ex);
	}
}
%>
<%
Session sess = null;
try {
	InitialContext initCtx = new InitialContext();
	Context envCtx = (Context) initCtx.lookup("java:comp/env");
	Repository repo = (Repository) envCtx.lookup("jcr/local/Cars");
	sess = repo.login(new SimpleCredentials("readwrite", "readwrite".toCharArray()));

	// Do something interesting with the Session ...
	out.println(sess.getRootNode().getPrimaryNodeType().getName());
} catch (Exception ex) {
	ex.printStackTrace();
} finally {
	if (sess != null) sess.logout();
}
%>

Since this uses a servlet container, there is no JAAS implementation configured, so note the loading of IDTrust to create the JAAS realm. (To make this work in Tomcat, the security folder that contains the jaas.conf.xml, users.properties, and roles.properties needs to be moved into the %CATALINA_HOME% directory.)

Building against ModeShape via Maven

By far the easiest way to use ModeShape is to use Maven, because with just a few lines of code, Maven will automatically pull all the JARs and source for all of the ModeShape libraries as well as everything those libraries need. All of ModeShape's artifacts for each release are published in the new JBoss Maven repository under the "org.modeshape" group ID.

<repositories>
  <repository>
    <id>jboss</id>
    <url>http://repository.jboss.org/nexus/content/groups/public/</url>
  </repository>
</repositories>

<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-jcr</artifactId>
  <version>2.7.0.Final</version>
</dependency>

<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-clustering</artifactId>
  <version>2.7.0.Final</version>
</dependency>

<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-cnd</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-ddl</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshapce</groupId>
  <artifactId>modeshape-sequencer-images</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-classfile</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-java</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-mp3</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-msoffice</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-xml</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-teiid</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-text</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-sequencer-zip</artifactId>
  <version>2.7.0.Final</version>
</dependency>

<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-filesystem</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-infinispan</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-jcr</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-jbosscache</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-jdbc-metadata</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-store-jpa</artifactId>
  <version>2.7.0.Final</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-connector-svn</artifactId>
  <version>2.7.0.Final</version>
</dependency>

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-log4j12</artifactId>
  <version>1.6.1</version>
</dependency>
<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>1.2.16</version>
</dependency>

Building against ModeShape via JARs

If your application doesn't use Maven, you'll need to obtain the ModeShape JARs and place them onto your application's classpath. ModeShape provides a single download with all of the JARs for all ModeShape components and all dependencies. This file contains the following:

• modeshape-jcr-2.7.0.Final-jar-with-dependencies.jar contains all of the classes (except those under javax.jcr) necessary to run the core ModeShape JCR repository engine using the in-memory connector and the federating connector;

• one modeshape-connector-<type>-2.7.0.Final-jar-with-dependencies.jar for each type of connector, each containing all of the classes necessary for that connector, designed to be added to the classpath after the modeshape-jcr-2.7.0.Final-jar-with-dependencies.jar file;

• one modeshape-sequencer-<type>-2.7.0.Final-jar-with-dependencies.jar for each type of connector, each containing all of the classes necessary for that sequencer, designed to be added to the classpath after the modeshape-jcr-2.7.0.Final-jar-with-dependencies.jar file;

• modeshape-mimetype-detector-aperture-2.7.0.Final-jar-with-dependencies.jar containing all of the classes necessary for detecting the MIME type of files based upon their name and/or content, designed to be added to the classpath after the modeshape-jcr-2.7.0.Final-jar-with-dependencies.jar file;
  Note that the core engine is required in all configurations. The jcr-2.0.jar file is not included and must be provided by you. And, as mentioned in the previous section, ModeShape uses SLF4J for logging and you must provide a logging implementation as well as the appropriate SLF4J binding JAR.